home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / source.lha / Geomview / doc / geomview-5 < prev    next >
Text File  |  1993-12-06  |  38KB  |  936 lines
  1. Info file: geomview,    -*-Text-*-
  2. produced by texinfo-format-buffer
  3. from file: geomview.tex
  4.  
  5.  
  6. 
  7. File: geomview  Node: OOGL.m, Prev: Mathematica, Up: Mathematica, Next: Geomview.m
  8.  
  9. Using Mathematica to generate OOGL files
  10. ========================================
  11.  
  12. The package `OOGL.m' allows Mathematica to write graphics objects in
  13. OOGL format.  To use it, give the command `<< OOGL.m' to Mathematica to
  14. load the package.  The `WriteOOGL[FILE,GRAPHICS]' command writes an OOGL
  15. description of the 3D graphics object GRAPHICS to the file named FILE.
  16.  
  17. This package also provides the `Geomview' command which sends a
  18. 3D graphics object to Geomview.  The first time you use this command
  19. it starts up a copy of Geomview.  Later calls send the graphics to the
  20. same Geomview.  There are two ways to use the `Geomview' command.
  21.  
  22. `Geomview[GRAPHICS]'
  23.      Sends the 3D graphics object GRAPHICS to Geomview as a geom named
  24.      `Mathematica'.  Subsequent usage of `Geomview[GRAPHICS]'
  25.      replaces the `Mathematica' object in Geomview with the new
  26.      GRAPHICS.
  27.  
  28. ``Geomview[NAME,GRAPHICS]''
  29.      Sends the 3D graphics object GRAPHICS to Geomview as a geom named
  30.      NAME.  You can use multiple calls of this form with different
  31.      names to cause Geomview to display several Mathematica objects at once
  32.      and allow independent control over them.
  33.      % math
  34.      Mathematica 2.0 for SGI Iris
  35.      Copyright 1988-91 Wolfram Research, Inc.
  36.       -- GL graphics initialized --
  37.  
  38.      In[1] := <<OOGL.m
  39.  
  40.      In[2] := Plot3D[Sin[x + Sin[y]], {x,-2,2},{y,-2,2}]
  41.  
  42.      Out[2] := -Graphics3D-
  43. This displays graphics in the usual Mathematica way here.
  44.      In[3] := WriteOOGL["math.oogl", %2]
  45.  
  46.      Out[3] := -Graphics3D-
  47. This displays nothing new but writes the file `math.oogl'.
  48. You can now load that file into Geomview on any computer.  Alternately,
  49. you can use the `Geomview' command to start up a copy of Geomview
  50. from within Mathematica.
  51.      In[5] := Geomview[%2]
  52.  
  53.      Out[5] := -Graphics3D-
  54.  
  55.  
  56. 
  57. File: geomview  Node: Geomview.m, Prev: OOGL.m, Up: Mathematica, Next: RenderMan
  58.  
  59. Using Geomview as Mathematica's Default 3D Display
  60. ==================================================
  61.  
  62. The package `Geomview.m' arranges for Geomview to be the
  63. default display program for 3D graphics in Mathematica.  To
  64. load it, give the command `<< Geomview.m' to Mathematica.
  65. Thereafter, whenever you display 3D graphics with `Plot3D'
  66. or `Show', Mathematica will send the graphics to Geomview.
  67.  
  68. Loading `Geomview.m' implicitly loads `OOGL.m' as well, so you
  69. can use the `Geomview' and `WriteOOGL' as described above
  70. after loading `Geomview.m'.  You do not have to separately load
  71. `OOGL.m'.
  72.      % math
  73.      Mathematica 2.0 for SGI Iris
  74.      Copyright 1988-91 Wolfram Research, Inc.
  75.       -- GL graphics initialized --
  76.  
  77.      In[1] := <<Geomview.m
  78.  
  79.      In[2] := Plot3D[x^2 + y^2, {x, -2, 2}, {y, -2, 2}]
  80.  
  81.      Out[2] := -SurfaceGraphics-
  82. This invokes geomivew and loads the graphics object into it.
  83.      In[3] := Plot3D[{x*y + 6, RGBColor[0,x,y]}, {x,0,1}, {y,0,1}]
  84.  
  85.      Out[3] := -SurfaceGraphics-
  86. This replaces the previous Geomview object by the new object. 
  87.      In[4] := Geomview[{%2,%3}]
  88.  
  89.      Out[4] := {-SurfaceGraphics-, -SurfaceGraphics-}
  90. This displays both objects at once.  You also can have more than one
  91. Mathematica object at a time on display in Geomview, and have separate
  92. control over them, by using the `Geomview' command with a name,
  93. *Note OOGL.m::.
  94.      In[5] := Graphics3D[ {RGBColor[1,0,0], Line[{ {2,2,2},{1,1,1} }] }]
  95.  
  96.      Out[5] := -Graphics3D-
  97.  
  98.      In[6] := Geomview["myline", %5]
  99. This addes the `Line' specified in `In[5]' to the existing
  100. Geomview display.  It can be controlled independently of the
  101. "Mathematica" object, which is currently the list of two plots.
  102.      In[7] := <<GL.m
  103. If you're on an SGI, loading `GL.m' returns Mathematica to its
  104. usual 3D graphics display.  To do this on a NeXT you should load
  105. `PSDirect.m' if you are using Mathematica in a notebook, or
  106. `NeXT.m' if you invoked Mathematica from a shell.  The following
  107. plot will appear in a normal static Mathematica window.
  108.      In[8] := ParametricPlot3D[{Sin[x],Sin[y],Sin[x]*Cos[y]}, {x,0,Pi},{y,0,Pi}]
  109.  
  110.      Out[8] := -Graphics3D-
  111. We can return to Geomview graphics at any time by reloading `Geomview.m'.
  112.      In[9] := <<Geomview.m
  113.  
  114.      In[10] := Show[%8]
  115.  
  116.      Out[10] := -Graphics3D-
  117.  
  118.      In[11] := ParametricPlot3D[
  119.             {(2*(Cos[u] + u*Sin[u])*Sin[v])/(1 + u^2*Sin[v]^2),
  120.             (2*(Sin[u] - u*Cos[u])*Sin[v])/(1 + u^2*Sin[v]^2),
  121.             Log[Tan[v/2]] + (2*Cos[v])/(1 + u^2*Sin[v]^2)},
  122.            {u,-4,4},{v,.01,Pi-.01}]
  123.  
  124.      Out[11] := -Graphics3D-
  125. This last plot is Kuen's surface, a surface of constant negative
  126. curvature.  Parametrization from Alfred Gray's *Modern Differential
  127. Geometry of Curves and Surfaces* textbook.
  128.  
  129. 
  130. File: geomview  Node: RenderMan, Prev: Geomview.m, Up: Mathematica, Next: Remote Display
  131.  
  132. Using Mathematica to generate RenderMan files
  133. =============================================
  134.  
  135. In addition to the `WriteOOGL' and `Geomview' commands
  136. described above, the package `OOGL.m' also defines the command
  137. `WriteRIB' which writes a 3D graphics object to a RenderMan RIB
  138. file:  `WriteRIB[FILE, GRAPHICS]' writes GRAPHICS
  139. to file FILE.  RenderMan is a commercial rendering system available
  140. from Pixar, Inc., which can produce extremely high quality images.
  141.      In[1] := <<OOGL.m
  142.  
  143.      In[2] := <<Graphics/Polyhedra.m
  144.  
  145.      In[3] := Graphics3D[Cube[]]
  146.  
  147.      Out[3] := -Graphics3D-
  148.  
  149.      In[4] := WriteRIB["cube.rib", %3]
  150.  
  151.      Out[4] := -Graphics3D- This generates the file `math.rib'.  This is
  152. a ready-to-render RIB file of the given geometry, using a default camera
  153. position, lighting, and the "plastic" shader. In a shell window, type
  154. `render cube.rib' to generate the image file `mma.tiff'. Of course, you
  155. need to have RenderMan installed for this to work. A shortcut to render
  156. from inside Mathematica is `WriteRIB["!render", foo]'.
  157.  
  158. `WriteRIB' works by first converting the Mathematica graphics
  159. object to OOGL format using `WriteOOGL' and then calls an external
  160. program `oogl2rib' to convert OOGL to RIB format.  The
  161. oogl2rib program takes several options which you can specify in a
  162. string as an optional third argument to `WriteRIB'.  The default
  163. option string is `" -n mma.tiff "', which indicates that the RIB
  164. file should generate a rendered TIFF file named `mma.tiff'.  A
  165. particularly useful option is `-g', which tells oogl2rib to
  166. convert only the geometry into a RIB fragment. You can insert that
  167. fragment into a full RIB file of your own making with camera positions
  168. and shaders of your choice, to harness the full power of RenderMan.
  169.  
  170. The full usage of oogl2rib is:
  171.      oogl2rib [-n NAME] [-B R,G,B] [-w WIDTH] [-h HEIGHT] [-fgb] [INFILE] [OUTFILE]
  172. By default it reads from stdin and writes to stdout.
  173. Either INFILE or OUTFILE may be `-', which means
  174. use stdin/stdout.  The options are:
  175.  
  176. `-n NAME'
  177.      Use NAME for the name of the rendered TIFF file (default
  178.      "geom.tiff") or framebuffer window (default "geom.rib").
  179.  
  180. `-B R,G,B'
  181.      Use background color (R,G,B).  Each component ranges
  182.      from 0 to 1. Default: none.
  183.  
  184. `-w WIDTH -h HEIGHT'
  185.      Rendered frame will be WIDTH by HEIGHT pixels.
  186.  
  187. `-f'
  188.      RIB file renders to on-screen framebuffer instead of TIFF file.
  189.  
  190. `-g'
  191.      Output only the geometry in RIB format.
  192.  
  193. `-b'
  194.      Output only a Quick Renderman clip object.  Ignores -nBwhf.
  195.  
  196.  
  197.  
  198. 
  199. File: geomview  Node: Remote Display, Prev: RenderMan, Up: Mathematica, Next: Networked Geomview
  200.  
  201. Using Geomview and Mathematica on Different Computers
  202. =====================================================
  203.  
  204. It is possible to use Geomview to display graphics generated by
  205. Mathematica running on a different computer.  If each computer is either
  206. an SGI or a NeXT and they are networked together, you can tell
  207. Mathematica to use a remote host for Geomview graphics.  If you want to
  208. use Mathematica on a computer that is not networked with your Geomview
  209. computer, or on any kind of computer other than an SGI or a NeXT (for
  210. example a PC or a Mac), you can write out *chunk* files in
  211. Mathematica which you transfer to the Geomview computer and then
  212. translate to OOGL format.
  213.  
  214. * Menu:
  215.  
  216. * Networked Geomview::    Using a networked Geomview host.
  217. * Chunks::        Transporting Mathematica files to Geomview by Hand.
  218.  
  219. 
  220. File: geomview  Node: Networked Geomview, Prev: Remote Display, Up: Remote Display, Next: Chunks
  221.  
  222. Using a Networked Geomview Host
  223. -------------------------------
  224.  
  225. The `Geomview' command looks at the `DISPLAY' or
  226. `REMOTEHOST' environment variables to try to determine if you are
  227. logged in from another computer.  If either of these indicates that you
  228. are, `Geomview' will attempt to run Geomview on that
  229. computer.  In order for this to work, your network must be configured
  230. such that the Mathematica computer can successfully `rsh' to the
  231. Geomview computer without giving a password.
  232.  
  233. You can also explicitly set the `DisplayHost' option to the
  234. `Geomview' command to a string which is the desired hostname, for
  235. example:
  236.      In[1] := << OOGL.m
  237.  
  238.      In[2] := Plot3D[Sin[x + Sin[y]], {x,-2,2},{y,-2,2}]
  239.  
  240.      Out[2] := -Graphics3D-
  241.  
  242.      In[3] := Geomview[%3, DisplayHost->"riemann"] This displays the
  243. graphics `%3' on the remote host named `riemann'.
  244.  
  245. `Geomview' recognizes the string `"local"' as a value for
  246. `$DisplayHost'; it forces the graphics to be displayed on the local
  247. machine.
  248.  
  249. In addition to knowing the name of the machine you want to run Geomview
  250. on, the `Geomview' needs to know the type of that machine (SGI or NeXT).
  251. By default, `Geomview' assumes that it is the same kind of computer as
  252. the one you are running Mathematica on.  The `MachType' option lets you
  253. explicitly specify the type of the `DisplayHost' computer; it should be
  254. one of the strings `"sgi"' or `"next"'.
  255.  
  256. You can use `SetOptions' to change the default `DisplayHost'
  257. and `MachType'.  For example,
  258.      In[4] := SetOptions[Geomview, DisplayHost->"riemann",
  259. MachType->"sgi"] arranges for `Geomview' to run Geomview on an SGI
  260. workstation named `riemann'.
  261.  
  262. 
  263. File: geomview  Node: Chunks, Prev: Networked Geomview, Up: Remote Display, Next: Package Details
  264.  
  265. Transporting Mathematica Files to Geomview by Hand
  266. --------------------------------------------------
  267.  
  268. The auxilliary function `WriteChunk' is for those who can only use
  269. Mathematica on a non-Unix machine (Mac, PC) or a Unix machine that is
  270. not on a network with an SGI or NeXT.  `WriteChunk[FILE, GRAPHICS]'
  271. generates a file named FILE which contains the graphics object GRAPHICS
  272. in the format accepted by `math2oogl'.
  273.  
  274. You can transfer that file to a computer that has Geomview installed on
  275. it and then use the programs `math2oogl', `oogl2rib', and
  276. `geomview' directly from the shell.  These programs are distributed
  277. in the `bin/sgi' (on SGIs) or `bin/next' (on NeXTs)
  278. subdirectory of the Geomview directory, and may have been installed so
  279. that they are on your `path'. 
  280.  
  281.      In[1]:= <<OOGL.m
  282.  
  283.      In[2]:= Plot3D[ Sin[x + Sin[y]], {x,-2,2}, {y,-2,2} ]
  284.  
  285.      Out[2]= -SurfaceGraphics-
  286.  
  287.      In[3]:= WriteChunk["mychunk",%2]
  288. This writes the file `mychunk' which contains a description
  289. of the graphics object.  You can then transfer this file to an SGI or
  290. NeXT and type
  291.      math2oogl < mychunk > mma.oogl
  292. to convert it to the OOGL file `mma.oogl' which you can then view
  293. using Geomview. This is the equivalent of the `WriteOOGL' command. 
  294.  
  295. For a result equivalent to the `Geomview' or `Show'
  296. commands, type
  297.      math2oogl -togeomview Mathematica geomview < mychunk
  298.  
  299. The `WriteRIB' command can be emulated from the shell as
  300.      math2oogl < mychunk | oogl2rib -n mma.tiff
  301.  
  302.  
  303.  
  304.  
  305. 
  306. File: geomview  Node: Package Details, Prev: Chunks, Up: Mathematica, Next: Package Installation
  307.  
  308. Details of the Mathematica->Geomview Package
  309. ============================================
  310.  
  311. The `OOGL.m' package uses the external program `math2oogl' to
  312. convert `Graphics3D' objects to OOGL format, because a compiled
  313. external program is able to do this conversion many times faster than
  314. Mathematica.
  315.  
  316. The converter will sometimes handle colored SurfaceGraphics objects
  317. correctly that Mathematica does not handle correctly, which means that
  318. Geomview[object] sometimes works where Show[object] will give errors.
  319.  
  320. The converter supports the `Polygon', `Line', and `Point'
  321. graphics primitives, `RGBColor Graphics3D' directives, and
  322. `SurfaceGraphics' objects with or without `RGBColor'
  323. directives, and lists of any combination of these. It silently ignores
  324. all other directives.
  325.  
  326. The Mathematica to RenderMan conversion is actually a two-step process:
  327. Mathematica->OOGL (math2oogl), and OOGL->RenderMan (oogl2rib). The
  328. math2oogl program has only been tested on SGIs and NeXTs, but could
  329. theoretically compile on any machine. The oogl2rib program depends on
  330. the OOGL (Object Oriented Graphics Language) libraries, which now only
  331. exist on SGI and NeXT machines.
  332.  
  333. In the `WriteOOGL' and `WriteRIB' commands, filename can either be a
  334. string containing a filename, an `OutputStream' object, or a string
  335. starting with a `!' to send the output to a command.  Object can be a
  336. `Graphics3D' object, a `SurfaceGraphics' object, or a list of these.
  337.  
  338. The packages work best with Mathematica 2.0 or better.  With version 1.2,
  339. the Geomview display is always on the local host. 
  340.  
  341. 
  342. File: geomview  Node: Package Installation, Prev: Package Details, Up: Mathematica, Next: Installation
  343.  
  344. Installing the Mathematica Packages
  345. ===================================
  346.  
  347. If Geomview is properly installed on your system according to the
  348. instructions in *Note Installation::, then the Mathematica-to-Geomview
  349. packages should work as described here; there should be no need for
  350. additional installation procedures.  In practice, however, it is
  351. sometimes necessary to taylor the installation of the Mathematica
  352. packages and/or of Geomview itself to suit the needs of a particular
  353. system.  This section contains details about how the installation works;
  354. if the Mathematica-to-Geomview connection does not seem to work for you
  355. after following the Geomview installation procedure, consult this
  356. section to see what might need to be fixed.
  357.  
  358. In this section, the phrase *Geomview installation* refers any of
  359. the procedures in *Note Installation::.  The way the Mathematica packages
  360. work and are installed is the same regardless of whether you have
  361. one of the binary distributions or the source distribution.
  362.  
  363.  
  364.   1. The relevant mathematica files are `OOGL.m', `Geomview.m', and
  365.      `BezierPlot.m'; Mathematica must be able to find these files.  They
  366.      are distributed in the `$GEOMROOT/mathematica' subdirectory of the
  367.      binary distributions, and in the
  368.      `$GEOMROOT/src/bin/geomutil/math2oogl' subdirectory of the source
  369.      distribution.  These files need to be in a directory that is on
  370.      Mathematica's search path.  You can look at the value of the
  371.      `$Path' variable in a Mathematica session on your system to see a
  372.      list of the directories on Mathematica's search path.
  373.  
  374.      The Geomview installation procedure puts copies of the Mathematica
  375.      packages into a directory that you specify (`MMAPACKAGEDIR').  This
  376.      should ensure that Mathematica can find them.  Alternately, you could
  377.      arrange to append the pathname of the Mathmematica package subdirectory
  378.      of the Geomview distribution to the `$Path' variable each time you
  379.      run Mathematica.
  380.  
  381.   2. The package `OOGL.m' needs to be able to invoke the programs
  382.      `geomview', `math2oogl', and `oogl2rib'.  The Geomview
  383.      installation procedure installs these programs into a directory that you
  384.      specify for executables (`BINDIR').  Ideally, this directory should
  385.      be on your shell's `$path'.  More specifically, it should be on
  386.      the `$path' of the shell in which Mathematica runs; the directory
  387.      `/usr/local/bin' is usually a good choice.  You can see the list of
  388.      directories on this path by giving the command `!echo $path' in
  389.      Mathematica.
  390.  
  391.      If for some reason you can't arrange for `geomview',
  392.      `math2oogl', and `oogl2rib' to be in a directory on the
  393.      shell's `$path', you can modify `OOGL.m' to cause it to look
  394.      for them using absolute pathnames.  To do this, change the definitions
  395.      of the variables `$GeomviewPath' and `$GeomRoot', which are
  396.      defined near the top of the file.  Change `$GeomviewPath' to the
  397.      absolute pathname of the `geomview' shell script on your system.
  398.      Change `$GeomRoot' to the absolute pathname of the
  399.      `$GEOMROOT' directory on your system.  If you do this, you should
  400.      also make sure there are copies of `geomview', `math2oogl',
  401.      and `oogl2rib' in the `$GEOMROOT/bin/sgi' (on an SGI) or
  402.      `$GEOMROOT/bin/next' (on a NeXT) directory.
  403.  
  404.   3. The `geomview' shell script, which `OOGL.m' uses to invoke
  405.      Geomview, needs to be able to find the geomview executable file (which
  406.      is called `gvx' on the SGI and `Geomview.app/Geomview' on the
  407.      NeXT).  The Geomview installation procedure should have been taken care
  408.      of this, but if your Mathematica session doesn't seem to be able to
  409.      invoke Geomview, it's worth double-checking that the settings in the
  410.      `geomview' script are correct.
  411.  
  412.  
  413. 
  414. File: geomview  Node: Installation, Prev: Package Installation, Up: Top, Next: SGI Binary Installation
  415.  
  416. Installation
  417. ************
  418.  
  419. What you do to install Geomview depends on which kind of computer you
  420. have (SGI or NeXT) and on whether you have the source distribution or
  421. the binary distribution.
  422.  
  423. In general, if you don't care about looking at Geomview's source code,
  424. you should get the binary distribution.  Its installation is much easier
  425. and quicker than that for the source code.
  426.  
  427. * Menu:
  428.  
  429. * SGI Binary Installation::   Installing the SGI Binary Distribution.
  430. * NeXT Binary Installation::  Installing the NeXT Binary Distribution.
  431. * Source Code Installation::  Compiling and Installing the Source Code Distribution.
  432. * Obtaining::        Obtaining Geomview.
  433.  
  434. 
  435. File: geomview  Node: SGI Binary Installation, Prev: Installation, Up: Installation, Next: SGI Binary Detail
  436.  
  437. Installing the SGI Binary Distribution
  438. ======================================
  439.  
  440. If you have just obtained a copy of the SGI binary distribution (file
  441. `geomview-sgi.tar.Z'), you should be able to run Geomview and make
  442. use of most of its features immediately after unpacking it by
  443. `cd''ing to the directory that it is in and typing `geomview'.
  444.  
  445. In order to fully install Geomview so that you can run it from any
  446. directory and use all of its features, follow the steps in this section.
  447. In particular, you must go through this installation procedure in order
  448. to use Geomview to display Mathematica graphics.
  449.  
  450. Geomview is distributed in a directory that contains various files and
  451. subdirectories that Geomview needs at run-time, such as data files and
  452. external modules.  It also contains other things distributed with
  453. Geomview, such as documentation and (in the soure-code distribution)
  454. source-code.  We refer to the root directory of this tree as the
  455. `$GEOMROOT' directory.  This is the directory called `Geomview'
  456. that is created when you unpack the distribution file.
  457.  
  458. To install Geomview on your system, arrange for the `$GEOMROOT'
  459. directory to be in a permanent place.  Then, in a shell window,
  460. `cd' to that directory and type `install'.  This runs a shell
  461. script which does the installation after asking you several questions
  462. about where you want to install the various components of Geomview.
  463.  
  464. After running the `install' script you should now be able to run
  465. Geomview from any directory on your system.  (You may need to give the
  466. `rehash' command in any shells on your computer that were started
  467. up before you did the installation.)
  468.  
  469.  
  470. The `install' script puts copies of the files in
  471. `$GEOMROOT/bin/sgi' and `$GEOMROOT/man' into the directories
  472. you specified for executables and man pages, respectively.  Once you
  473. have done the installation you can cut down one the disk space required
  474. by Geomview by removing some files from these directories, since copies
  475. have been installed elsewhere.  You should first test that your
  476. installed Geomview works properly because once you remove these files
  477. from their distribution directories you will not be able to do the
  478. installation again.
  479.  
  480. In particular, the files you can remove are
  481.  
  482.  
  483. `$GEOMROOT/bin/sgi':
  484.      Remove all files from here except `gvx', which is the geomview
  485.      executable file.  DO NOT REMOVE `gvx'.  It is not installed
  486.      elsewhere.
  487.  
  488. `$GEOMROOT/man':
  489.      You can remove all the files in this directory.
  490.  
  491.  
  492.  
  493. 
  494. File: geomview  Node: SGI Binary Detail, Prev: SGI Binary Installation, Up: SGI Binary Installation, Next: NeXT Binary Installation
  495.  
  496. Details of the SGI Binary Installation
  497. --------------------------------------
  498.  
  499. The `install' script should be self-explanatory; just run it and
  500. answer the questions.  This section gives some details for system
  501. administrators and other users who may want to know more about the
  502. installation. 
  503.  
  504. The installation is actually done by `make'; the `install'
  505. script queries the user for the settings of the following `make'
  506. variables and then invokes `make install'.
  507.  
  508.  
  509. `GEOMROOT':
  510.      the absolute pathname of the Geomview root directory.  The
  511.      `geomview' shell script, which is what users invoke to run
  512.      Geomview, uses this to set various environment variables that Geomview
  513.      needs.  It is very important that this be an *absolute* pathname
  514.      --- i.e. it should start with a '/'.
  515.  
  516. `BINDIR':
  517.      a directory where executable files are installed.  The `geomview'
  518.      shell script goes here, as well as various other auxiliary programs that
  519.      can be used in conjunction with `geomview'.  This should be a
  520.      directory that is on users' `$path'.  These auxiliary programs are
  521.      distributed in the `$GEOMROOT/bin/sgi' directory; if you specify
  522.      this directory for `BINDIR', they are left in that directory.
  523.  
  524. `MANDIR':
  525.      a directory where Unix manual pages are installed.  These are
  526.      distributed in the `$GEOMROOT/man' subdirectory; if you specify
  527.      this directory for `MANDIR', they are left in that directory.
  528.  
  529. `MMAPACKAGEDIR':
  530.      a directory where Mathematica packages are installed.  This should be a
  531.      directory that Mathematica searches for packages that it loads; you can
  532.      see what directories your Mathematica searches by looking at the value
  533.      of the `$Path' variable in a Mathematica session.  The
  534.      installation process will install some packages there which allow you to
  535.      use Geomview to display Mathematica graphics.  These packages are
  536.      distributed in the `$GEOMROOT/mathematica' subdirectory; if you
  537.      specify this directory for `MMAPACKAGEDIR', or if you specify the
  538.      empty string for `MMAPACKAGEDIR', the packages are left in that
  539.      directory.  For more details about the way these Mathematica packages
  540.      connect to Geomview, *Note Package Installation::.
  541.  
  542.  
  543. 
  544. File: geomview  Node: NeXT Binary Installation, Prev: SGI Binary Detail, Up: Installation, Next: NeXTStep Binary Detail
  545.  
  546. Installing the NeXT Binary Distribution
  547. =======================================
  548.  
  549.  
  550.   1. If you have just obtained a copy of the NeXTStep binary distribution
  551.      (file `geomview-next.tar'), you can unpack it by double-clicking on
  552.      it in the Workspace.  This will open up a File Viewer panel showing,
  553.      among other things, a NeXT Installer package called `Geomview.pkg'.
  554.  
  555.  
  556.   2. The first thing you should do is double-click on `Geomview.pkg' to
  557.      invoke the NeXT Installer.  You will be asked where you want to install
  558.      it; typically it should go in `/LocalApps' or in `~/Apps' in
  559.      your home directory.  You should now be able to run Geomview and make
  560.      use of most of its features by double-clicking on the installed
  561.      `Geomview.app' icon.
  562.  
  563.   3. There are some aspects of the installation, however, that the NeXT
  564.      Installer can't handle.  In order to fully install Geomview so that you
  565.      can use all of its features, you should run the `install' script in
  566.      the `Geomview.app' directory. In particular, you must go through
  567.      this installation procedure in order to use Geomview to display
  568.      Mathematica graphics.
  569.  
  570.      To run the `install' script you can open `Geomview.app' in the
  571.      Workspace by selecting it and picking `File->Open as Folder' from
  572.      the Workspace menu.  This will pop up a File Viewer panel showing the
  573.      contents of `Geomview.app'.  Scroll down to the file named
  574.      `install', and double-click on it.  This will open a terminal
  575.      window and run the script in that window.  Alternately, you can open a
  576.      terminal window yourself, cd to `Geomview.app', and run
  577.      `install' there.
  578.  
  579.      The `install' script does the installation after asking you several
  580.      questions about where you want to install the various components of
  581.      Geomview.  After running the `install' script, Geomview is
  582.      completely installed.  If in the future you move `Geomview.app' to
  583.      some other location you should run `install' again.
  584.  
  585.   4. This step is optional.  Geomview's example data files are in the
  586.      `Geomview.app/data' directory.  If you are on a network with both
  587.      SGI workstations and NeXTStep workstations, and you want to install
  588.      Geomview to run on both, you can save disk space by having the two
  589.      installations share a common data directory.  To do this, decide on a
  590.      location for the data directory and copy it there if it isn't there
  591.      already (a good choice would be to leave it in the `$GEOMROOT'
  592.      directory in your SGI Geomview installation).  Then edit the file
  593.      `Geomview.app/CONFIG.gv' to change the setting of the variable
  594.      `GEOMVIEW_DATA' to point to this directory (there are comments in
  595.      the file telling you what to do).  You can then remove the data
  596.      directory from `Geomview.app'.
  597.  
  598.  
  599. To run geomview, double-click on `Geomview.app' from the workspace,
  600. or type `open Geomview.app' from the appropriate directory, or type
  601. `geomview' from a shell window.
  602.  
  603. More Geomview documentation is in the `Geomview.app/doc'
  604. subdirectory.  In particular, a copy of the manual is there.
  605.  
  606. The `install' script puts copies of the files in
  607. `Geomview.app/bin/next' and `Geomview.app/man' into the
  608. directories you specified for executables and man pages, respectively.
  609. Once you have done the installation you can cut down one the disk space
  610. required by Geomview by removing all the files in these directories,
  611. since copies have been installed elsewhere.  You should first test that
  612. your installed Geomview works properly because once you remove these
  613. files from their distribution directories you will not be able to do the
  614. installation again.
  615.  
  616. 
  617. File: geomview  Node: NeXTStep Binary Detail, Prev: NeXT Binary Installation, Up: NeXT Binary Installation, Next: Source Code Installation
  618.  
  619. Details of the NeXTStep Binary Installation
  620. -------------------------------------------
  621.  
  622. Other than the installation of the `Geomview.app' directory, the
  623. installation details of the NeXTStep binary distribution are the same as
  624. for the SGI distribution, *Note SGI Binary Detail::.  Note that the
  625. directory referred to in the SGI distribution as `$GEOMROOT'
  626. is the `Geomview.app' directory in the NeXTStep distribution.
  627.  
  628. 
  629. File: geomview  Node: Source Code Installation, Prev: NeXTStep Binary Detail, Up: Installation, Next: Obtaining
  630.  
  631. Compiling and Installing the Source Code Distribution
  632. =====================================================
  633.  
  634. The main reason to get the source code distribution is to look at and/or
  635. work with the source code.  If you are only concered with *using*
  636. Geomview it is better to get the binary distribution.  It takes anywhere
  637. from 15 minutes to 1.5 hours to compile the entire source distribution,
  638. depending on what kind of computer you have.
  639.  
  640. Let `$GEOMROOT' denote the full pathname of the Geomview source
  641. code directory; this is the directory called `Geomview' that is
  642. created when you unpack the distribution.  This directory contains the
  643. Geomview source code as well as various other files and subdirectories
  644. that Geomview needs when it runs.
  645.  
  646. Before doing any compilation you should edit the file
  647. `$GEOMROOT/makefiles/mk.site.default'.  This file defines some
  648. `make' variables which specify your local configuration.  This
  649. includes the pathnames of the directories into which Geomview will be
  650. installed, and possibly some other settings as well.  There are comments
  651. in the file telling you what to do.  This file is included by every
  652. Makefile in the source tree, so the settings you specify here are used
  653. throughout the source.
  654.  
  655. If you will be compiling for both SGI and NeXT, you can do both in the
  656. same directory tree.  By default the Makefiles are set up to put the
  657. objects files, libraries, and executables in directories which depend on
  658. the type of computer, so the two architectures will not interfere with
  659. each other.  The Makefiles use a variable called `CPU' to determine
  660. the type of machine. Before doing any compilation you must arrange for
  661. this variable to have a value.  There are two ways you can do this.
  662.  
  663.  
  664.   1. If you will always be compiling Geomview on the same type of computer
  665.      (SGI or NeXT), edit the file `$GEOMROOT/makefiles/Makedefs.global'
  666.      to set the `CPU' variable to either `iris4' or `NeXT'.
  667.      The comments near the top of that file will tell you where to do this.
  668.  
  669.   2. If you will be compiling on both types of computers you can set a shell
  670.      environment variable named `CPU' to either `iris4' or
  671.      `NeXT', and the Makefiles will inherit the value from the
  672.      environment.  The script `$GEOMROOT/config' determines which kind
  673.      of computer you are on and sets this variable accordingly.  To use this
  674.      script, type `source config' in the (assuming a C-shell type shell)
  675.      in the `$GEOMROOT' directory shell in which you plan to do the
  676.      compilation.  Or you can set the variable directly; it should be either
  677.      `NeXT' or `iris4'.  You will need to do this in every shell in
  678.      which you plan to do compilation.
  679.  
  680.      Alternately, you could modify your shell initialization file
  681.      (`.cshrc' or whatever) to set `CPU' appropriately.
  682.  
  683.  
  684. Note that many of the Makefiles refer to a variable called `MACHTYPE'
  685. to determine the type of machine.  This is set to either `sgi' or
  686. `next', depending on the value of `CPU'.
  687.  
  688. Once you have configured your source tree by editing the files as
  689. described above and setting the `CPU' variable, you can compile and
  690. install Geomview by typing `make install' in the `$GEOMROOT'
  691. directory.  You can also type `make all', or equivalently just
  692. `make', to compile without installing, and then type `make
  693. install' later to install.
  694.  
  695. You can use these same `make' comands in any subdirectory in the
  696. tree to recompile and/or install a part of Geomview or a module.
  697.  
  698. If you want to compile fat binaries under NeXTStep 3.1, before doing any
  699. compilation edit the file `$GEOMROOT/makefiles/mk.next' to
  700. uncomment a particular line there.  There are comments in the file
  701. telling you which line to uncomment.
  702.  
  703. If you want to modify the complier flags used during compilation, edit
  704. the file `$GEOMROOT/makefiles/Makedefs.global'; the `COPTS'
  705. variable specifies the flags passed to the C compiler (cc).
  706.  
  707. 
  708. File: geomview  Node: Obtaining, Prev: Source Code Installation, Up: Installation, Next: Function Index
  709.  
  710. Obtaining Geomview
  711. ==================
  712.  
  713. Geomview is available free via anonymous ftp from Internet host
  714. `geom.umn.edu', IP address 128.101.25.35.  The Geomview
  715. distribution files are in the `pub/software/geomview' subdirectory.
  716. They are all tar archive files (`.tar' or `.tar.Z' files), so
  717. you should use binary mode in ftp for transferring them to your site.
  718.  
  719. The main files are
  720.  
  721.  
  722. `geomview-sgi.tar.Z'
  723.      The SGI binary distribution. Contains executables for running
  724.      on any Silcon Graphics IRIS workstation, plus documentation
  725.      and example files.
  726.  
  727. `geomview-next.tar'
  728.      The NeXTStep binary distribution.  This contains fat binaries which
  729.      will run on either a NeXT workstation running NeXTStep 3.0 or 3.1,
  730.      or a 486 PC running NeXTStep 3.1.  Also contains documentation and
  731.      example files.  This {.tar} file is not compressed because it
  732.      contains the distribution compressed into a NeXT Installer package,
  733.      and further compression actually increases the size of the file.
  734.      To unpack `geomview-next.tar' on a NeXT, simple double-click on it
  735.      in the Workspace.
  736.  
  737. `geomview-src.tar.Z'
  738.      The source code distribution; contains source code so you can compile
  739.      Geomview and the distributed external modules on either an SGI or on a
  740.      NeXT workstation running NeXTStep 3.0 or 3.1, or a 486 PC running
  741.      NeXTStep 3.1.  Also contains documentaion and examples files.
  742.  
  743.  
  744. Each of the above archive files contains the entire distribution:
  745. executables or source for Geomview itself, plus all distributed external
  746. modules, example data files, and documentation.  These archive files are
  747. therefore rather large.  If you do not have enough disk space on your
  748. workstation for the entire distribution, various pieces of the
  749. distribution are available separately in the
  750. `pub/software/geomview/pieces' subdirectory.  See the file
  751. `README' in that directory for details.
  752.  
  753. After retrieving any of the distribution archive files, you can
  754. unpack it with a command like the following
  755.      % uncompress < geomview-sgi.tar.Z | tar xvopf -
  756. This will unpack the contents of the archive file into
  757. a subdirectory named `Geomview'.  Once unpacked, you
  758. can delete the archive file.
  759.  
  760. The following is a sample ftp session for retreiving and unpacking the
  761. SGI binary distribution.  After unpacking, see the file `README'
  762. for more information.
  763.  
  764.      artin% ftp geom.umn.edu
  765.      Connected to geom.umn.edu.
  766.      220 cameron FTP server (Version 5.88 Thu Jun 25 16:41:41 CDT 1992) ready.
  767.      Name (geom.umn.edu:mbp): anonymous
  768.      331 For password please enter your e-mail address or name and institution.
  769.      Password:mbp@geom.umn.edu
  770.  
  771.      230 Guest login ok, access restrictions apply.
  772.      ftp> cd pub/software/geomview
  773.      250 CWD command successful.
  774.      ftp> binary
  775.      200 Type set to I.
  776.      ftp> get geomview-sgi.tar.Z
  777.      200 PORT command successful.
  778.      150 Opening BINARY mode data connection for geomview-sgi.tar.Z (5815980 bytes).
  779.      226 Transfer complete.
  780.      local: geomview-sgi.tar.Z remote: geomview-sgi.tar.Z
  781.      5815980 bytes received in 28.67 seconds (1.98e+02 Kbytes/s)
  782.      ftp> quit
  783.      221 Goodbye.
  784.      artin% ls -l
  785.      total 5680
  786.      -rw-rw-r--  1 mbp      5815980 Aug 19 16:38 geomview-sgi.tar.Z
  787.      artin% uncompress < geomview-sgi.tar.Z | tar xvopf -
  788.      x ./CHANGES, 16910 bytes, 34 tape blocks
  789.      ...
  790.      artin% rm geomview-sgi.tar.Z
  791.  
  792.  
  793. 
  794. File: geomview  Node: Function Index, Prev: Obtaining, Up: Top
  795.  
  796. Function Index
  797. **************
  798.  
  799.  
  800. * Menu:
  801.  
  802. * !: Gcl Reference.
  803. * <: Gcl Reference.
  804. * =: Gcl Reference.
  805. * >: Gcl Reference.
  806. * ?: Gcl Reference.
  807. * ??: Gcl Reference.
  808. * |: Gcl Reference.
  809. * all: Gcl Reference.
  810. * ap-override: Gcl Reference.
  811. * backcolor: Gcl Reference.
  812. * bbox-color: Gcl Reference.
  813. * bbox-draw: Gcl Reference.
  814. * camera: Gcl Reference.
  815. * camera-draw: Gcl Reference.
  816. * camera-prop: Gcl Reference.
  817. * camera-reset: Gcl Reference.
  818. * car: Gcl Reference.
  819. * cdr: Gcl Reference.
  820. * clock: Gcl Reference.
  821. * command: Gcl Reference.
  822. * copy: Gcl Reference.
  823. * cull-backface: Gcl Reference.
  824. * cursor: Gcl Reference.
  825. * cursor-still: Gcl Reference.
  826. * cursor-twitch: Gcl Reference.
  827. * delete: Gcl Reference.
  828. * dice: Gcl Reference.
  829. * dimension: Gcl Reference.
  830. * draw: Gcl Reference.
  831. * echo: Gcl Reference.
  832. * emodule-clear: Gcl Reference.
  833. * emodule-define: Gcl Reference.
  834. * emodule-defined: Gcl Reference.
  835. * emodule-isrunning: Gcl Reference.
  836. * emodule-path: Gcl Reference.
  837. * emodule-run: Gcl Reference.
  838. * emodule-sort: Gcl Reference.
  839. * emodule-start: Gcl Reference.
  840. * emodule-transmit: Gcl Reference.
  841. * escale: Gcl Reference.
  842. * event-mode: Gcl Reference.
  843. * evert: Gcl Reference.
  844. * exit: Gcl Reference.
  845. * ezoom: Gcl Reference.
  846. * freeze: Gcl Reference.
  847. * geometry: Gcl Reference.
  848. * geomview-version: Gcl Reference.
  849. * hdefine: Gcl Reference.
  850. * help: Gcl Reference.
  851. * hmodel: Gcl Reference.
  852. * hsphere-draw: Gcl Reference.
  853. * if: Gcl Reference.
  854. * inhibit-warning: Gcl Reference.
  855. * interest: Gcl Reference.
  856. * lines-closer: Gcl Reference.
  857. * load: Gcl Reference.
  858. * load-path: Gcl Reference.
  859. * look: Gcl Reference.
  860. * look-encompass: Gcl Reference.
  861. * look-encompass-size: Gcl Reference.
  862. * look-recenter: Gcl Reference.
  863. * look-toward: Gcl Reference.
  864. * merge: Gcl Reference.
  865. * merge-ap: Gcl Reference.
  866. * merge-base-ap: Gcl Reference.
  867. * merge-baseap: Gcl Reference.
  868. * morehelp: Gcl Reference.
  869. * name-object: Gcl Reference.
  870. * ND-axes: Gcl Reference.
  871. * ND-color: Gcl Reference.
  872. * ND-xform: Gcl Reference.
  873. * new-alien: Gcl Reference.
  874. * new-camera: Gcl Reference.
  875. * new-center: Gcl Reference.
  876. * new-geometry: Gcl Reference.
  877. * new-reset: Gcl Reference.
  878. * NeXT: Gcl Reference.
  879. * normalization: Gcl Reference.
  880. * pick: Gcl Reference.
  881. * pickable: Gcl Reference.
  882. * position: Gcl Reference.
  883. * position-at: Gcl Reference.
  884. * position-toward: Gcl Reference.
  885. * progn: Gcl Reference.
  886. * quit: Gcl Reference.
  887. * quote: Gcl Reference.
  888. * rawevent: Gcl Reference.
  889. * rawpick: Gcl Reference.
  890. * read: Gcl Reference.
  891. * real-id: Gcl Reference.
  892. * redraw: Gcl Reference.
  893. * regtable: Gcl Reference.
  894. * rehash-emodule-path: Gcl Reference.
  895. * replace-geometry: Gcl Reference.
  896. * rib-display: Gcl Reference.
  897. * rib-snapshot: Gcl Reference.
  898. * scale: Gcl Reference.
  899. * scene: Gcl Reference.
  900. * set-clock: Gcl Reference.
  901. * set-conformal-refine: Gcl Reference.
  902. * set-emodule-path: Gcl Reference.
  903. * setenv: Gcl Reference.
  904. * set-load-path: Gcl Reference.
  905. * set-motionscale: Gcl Reference.
  906. * sgi: Gcl Reference.
  907. * shell: Gcl Reference.
  908. * sleep_for: Gcl Reference.
  909. * sleep-until: Gcl Reference.
  910. * snapshot: Gcl Reference.
  911. * soft-shader: Gcl Reference.
  912. * space: Gcl Reference.
  913. * stereowin: Gcl Reference.
  914. * time-interests: Gcl Reference.
  915. * transform: Gcl Reference.
  916. * transform-incr: Gcl Reference.
  917. * transform-set: Gcl Reference.
  918. * ui-center: Gcl Reference.
  919. * ui-panel: Gcl Reference.
  920. * ui-target: Gcl Reference.
  921. * uninterest: Gcl Reference.
  922. * update: Gcl Reference.
  923. * update-draw: Gcl Reference.
  924. * window: Gcl Reference.
  925. * winenter: Gcl Reference.
  926. * write: Gcl Reference.
  927. * write-sexpr: Gcl Reference.
  928. * xform: Gcl Reference.
  929. * xform-incr: Gcl Reference.
  930. * xform-set: Gcl Reference.
  931. * zoom: Gcl Reference.
  932.  
  933.  
  934.  
  935. 
  936.